Skip to main content

docusaurus

Here’s the thing, Abhinav — your list is the skeleton of a Docusaurus migration, but a real migration has a lot of connective tissue. Since you’re converting a raw Markdown project into a proper Docusaurus site, you want a checklist that covers project setup, content ingestion, site structure, styling, and deployment.

Below is a more granular, practical, “no‑surprises” migration checklist you can actually follow.

🧭 Full Migration Checklist: Raw Markdown → Docusaurus

1. Initialize the project​

  • npm init (or skip if using npx create-docusaurus@latest)
  • Install dependencies:
    • npm install @docusaurus/core @docusaurus/preset-classic react react-dom
  • Add TypeScript support:
    • npm install --save-dev typescript @types/react @types/node

2. Project structure setup​

Create the standard Docusaurus folders:

/docs
/src
  /components
  /css
/static
docusaurus.config.ts
sidebars.ts
tsconfig.json

3. Configure TypeScript​

  • Add a minimal tsconfig.json:
    • jsx: react-jsx
    • moduleResolution: bundler
    • allowJs: true (if you want JS + TS)
  • Add path aliases if you want cleaner imports.

4. Configure Docusaurus​

Edit docusaurus.config.ts:

  • Set title, tagline, favicon
  • Configure presets (docs, blog, theme)
  • Configure themeConfig:
    • Navbar
    • Footer
    • Prism code highlighting
    • Color mode (light/dark)
  • Add plugins if needed:
    • Search (Algolia)
    • Google Analytics
    • Local search plugin

5. Configure sidebars​

  • Create sidebars.ts
  • Choose between:
    • Autogenerated (recommended for Markdown migrations)
    • Manual (explicit ordering)

Example autogenerated:

export default {
  docs: [{ type: "autogenerated", dirName: "." }],
};

6. Import your Markdown content​

Move your existing Markdown files into /docs.

Then:

  • Fix relative links (../foo.md → /docs/foo)
  • Fix image paths (move images into /static/img)
  • Convert any non‑Markdown content (HTML, code samples, etc.)
  • Add frontmatter to each file:
---
title: My Page
description: Optional
---

7. Add custom components (optional but common)​

If your Markdown uses custom UI elements, create React components in /src/components and import them via MDX:

import MyComponent from "@site/src/components/MyComponent";

<MyComponent />

8. Styling & theme customization​

  • Edit /src/css/custom.css
  • Override theme components if needed:
    • /src/theme/Navbar
    • /src/theme/Footer
  • Add custom Prism themes for code blocks

9. Local development​

Run:

npm run start

Fix:

  • Broken links
  • Sidebar ordering
  • Missing images
  • MDX syntax errors

10. Build & test​

npm run build
npm run serve

Verify:

  • All pages render
  • No broken links
  • No missing assets
  • No hydration errors

11. Deployment​

Depending on your target:

GitHub Pages​

  • Add organizationName and projectName to config

  • Run:

    GIT_USER=abhinav npm run deploy

Vercel / Netlify​

  • Just point to the repo
  • Build command: npm run build
  • Output directory: build

🔍 Anything missing from your original list?

Yes — quite a bit.
Here are the major categories you didn’t include:

CategoryMissing Items
Content migrationFixing links, images, frontmatter, MDX conversion
Theme & stylingCustom CSS, component overrides
PluginsSearch, analytics, sitemap
Build & QABroken link checking, local testing
DeploymentGitHub Pages / Vercel / Netlify setup
Markdown → MDXHandling custom components, imports

Want me to turn this into a clean, actionable TODO list you can paste into your repo?

I can format it as:

  • A GitHub issue checklist
  • A Notion-style task board
  • A linear step-by-step migration plan

Just tell me the style you prefer.